home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
EnigmA Amiga Run 1995 October
/
EnigmA AMIGA RUN 01 (1995)(G.R. Edizioni)(IT)[!][issue 1995-10][Aminet 7].iso
/
Aminet
/
dev
/
gui
/
BGUI11c.lha
/
docs
/
baseclass.doc
next >
Wrap
Text File
|
1995-04-23
|
17KB
|
404 lines
File: baseclass.doc
Description: Baseclass documentation.
Copyright: (C) Copyright 1994-1995 Jaba Development.
(C) Copyright 1994-1995 Jan van den Baard.
All Rights Reserved.
------------------------------------------------------------------------------
TABLE OF CONTENTS
baseclass/--background--
baseclass/Methods
baseclass/Attributes
baseclass/--background-- baseclass/--background--
NAME
Class: baseclass
Superclass: GADGETCLASS
Include File: <libraries/bgui.h>
FUNCTION
This is the most important gadget class in BGUI. It is the superclass
of almost all the other gadget classes at one point or the other. It
will take care of the following things for it's subclasses:
o Notification
o Frames
o Labels
o Online-help.
If you plan on writing a class for BGUI then always sub-class in from
this class. That way you automatically inherrit the above mentioned
features.
baseclass/Methods baseclass/Methods
NOTE
The methods described here are also valid for the other BGUI gadget
classes subclassed from this class unless documented otherwise.
NEW METHODS
BASE_ADDMAP -- This method must be used to add a target object to an
object it's maplist notification list. Maplist notification
is simular to the notification performed by the system
"icclass" and ICA_TARGET notification. This method uses the
following custom message structure:
struct bmAddMap {
ULONG MethodID; /* BASE_ADDMAP */
Object *bam_Object; /* Target object */
struct TagItem *bam_MapList;
};
bam_MapList -- This can point to an array of TagItem
structures which contains a set of attributes to map. This
may also be NULL in which case no mapping is done.
Returns TRUE uppon success, FALSE uppon failure.
BASE_ADDCONDITIONAL -- This method must be used to add a target object
to an object it's conditional notification list. Conditional
notification is a simple "if attr a == b then set attr c to d"
style of notification. Example:
Object *cycle, *string;
DoMethod( cycle, BASE_ADDCONDITIONAL, string,
CYC_Active, 0,
GA_Disabled, FALSE,
GA_Disabled, TRUE );
This will enable the string gadget when the CYC_Active
attribute of the cycle gadget is 0. If the CYC_Active
attribute is not 0 the string gadget is disabled.
This method uses the following custom message structure:
struct bmAddConditional {
ULONG MethodID; /* BASE_ADDCONDITIONAL */
Object *bac_Object; /* Target object. */
struct TagItem bac_Condition;
struct TagItem bac_TRUE;
struct TagItem bac_FALSE;
};
bac_Condition -- This attribute pair represents the condition
which has to be met.
bac_TRUE -- This attribute pair is set to the target object if
the condition is TRUE (I.E. met).
bac_FALSE -- This attribute pair is set to the target object
if the condition is FALSE (I.E. not met).
Returns TRUE uppon success, FALSE uppon failure.
BASE_ADDMETHOD -- This method must be used to add a target object to
an object it's method notification list. Method notification
allows you to send a complete method to a target when a
notification event occures. This method uses the following
custom message structure:
struct bmAddMethod {
ULONG MethodID; /* BASE_ADDMETHOD */
Object *bam_Object; /* Target object. */
ULONG bam_Flags;
ULONG bam_Size;
ULONG bam_MethodID;
};
bam_Flags -- This may contain any of the following flags:
BAMF_NO_GINFO -- Normally a pointer to a GadgetInfo
structure is inserted in the method to send.
When this flag is set this will not be done.
Please note that when a GadgetInfo is placed
it is done as follows:
OM_NEW, OM_SET, OM_UPDATE, OM_NOTIFY -- If the
method to send is any of these the
GadgetInfo is placed in the third
long word of the method. All other
methods will get the GadgetInfo in the
second long word. This behaviour is
the same as with DoGadgetMethodA().
BAMF_NO_INTERIM -- When set the method will not be
send on interim notification events.
bam_Size -- This field must contain the number of long-words
_including_ the method ID of the method to send. This
information is needed because a copy of the method to
send is made in an internal buffer.
bam_MethodID -- This must be the ID of the method to send.
This field can be followed by the method specific
data.
Please note that most notification will occure on the
input.device it's task. This means that the called method must
not take to long to return and generally should not do
anything a normal input handler should not do.
Returns TRUE uppon success, FALSE uppon failure.
BASE_REMMAP, BASE_REMCONDITIONAL, BASE_REMMETHOD, BASE_REMHOOK --
These methods must be used to remove a target object/hook from
any of the notification lists. This method uses the following
message structure:
struct bmRemove {
ULONG MethodID; /* Any of the above. */
Object *bar_Object; /* Object to remove. */
};
Return code not defined.
BASE_SETLOOP, BASE_CLEARLOOP, BASE_CHECKLOOP, BASE_LEFTEXT,
BASE_SHOWHELP -- These methods are private and should not be of any
use to you.
BASE_ADDHOOK -- This method must be used to add a hook routine to the
object it's hook-notification list. Hook notification allows
you to add a routine via a Hook to the notification of the
object. In other words, the hook will be called whenever the
object sends out a notification. This method uses the
following custom message structure:
struct bmAddHook {
ULONG MethodID; /* BASE_ADDHOOK */
struct Hook *bah_Hook;
};
bah_Hook -- A pointer to the Hook structure.
Your hook routine will be called as follows:
rc = hookFunc( hook, obj, update );
D0 A0 A2 A1
hook -- This will point to the Hook structure.
obj -- This is a pointer to the object that caused the
notification.
update -- This is a pointer to a opUpdate structure from which
you can extract data like the visual environment and
notified attribute changes.
Your hook routine must return non-zero when the notification
caused a change of some sort and zero if not.
Returns TRUE uppon success and FALSE uppon failure.
SEE ALSO
intuition.library/DoGadgetMethodA(), icclass, ICA_TARGET,
utility/hooks.h
CHANGED METHODS
OM_UPDATE -- This method fixes a bug in the system GADGETCLASS. Even
though the documentation states that the GA_ID attribute of a
gadget object cannot be changed by a OM_UPDATE message it
still does. As this behaviour is not correct the baseclass
intercepts the GA_ID attribute before passing it on to the
GADGETCLASS. This way GA_ID will not be changable by a
OM_UPDATE call.
OM_NOTIFY -- This method will first execute all maplist, conditional,
method and hook notification. When that is done the method
is passed onto GADGETCLASS for any ICA_TARGET's that might
still exist.
GM_RENDER -- If this message requests a complete re-rendering (I.E.
GREDRAW_REDRAW) this method will render the frame and label
when available. On any other request it will simply re-compute
the gadget hitbox bounds. When this method returns a non-NULL
value you are also allowed to render. If this method returns
NULL then you may not render.
Your class _must_ also follow the same rules. If the
superclass of your class returns NULL you do not render and
also return NULL. If the superclass of your class returns a
non-NULL value you should render and also return a non-NULL
value.
Your class must use the gpr_RPort field for _all_ rendering.
This usually points to a buffer rastport in which you render
without it showing on screen. This also means that if your
class uses OM_SET on another object you must do so without
passing the gpr_GInfo field and re-render that object later in
the RastPort pointed to by the gpr_RPort field.
RastPort-Clipping is not allowed for BGUI objects. The reason
for this limitation is that all rendering occures in a buffer
rastport without a layer attached to it. If your class
absolutely needs clipping you must use the WINDOW_NoBufferRP
or PAGE_NoBufferRP on the window object or page object in
which the object is located.
GM_HITTEST -- This method will return GMR_GADGETHIT when the gadget
was clicked inside it's hitbox bounds.
SEE ALSO
<intuition/gadgetclass.h>
baseclass/Attributes baseclass/Attributes
NOTE
The attributes described here are also valid for the other BGUI gadget
classes subclassed from this class unless documented otherwise.
NAME
BT_HelpFile -- ( STRPTR )
FUNCTION
Set the name of the file to be displayed when a help-request for the
object arives. Please note that the full path-name must be given.
Default is NULL. Applicability is (IS).
SEE ALSO
BT_HelpNode, BT_HelpLine
NAME
BT_HelpNode -- ( STRPTR )
FUNCTION
Set the name of the node which is diplayed in the help window.
Default is NULL. Applicability is (IS).
SEE ALSO
BT_HelpFile, BT_HelpLine
NAME
BT_HelpLine - ( ULONG )
FUNCTION
Set the line number from which the file is displayed. This may be
useful if the help-file is not an AmigaGuide file.
Default is 0. Applicability is (IS).
SEE ALSO
BT_HelpFile, BT_HelpNode
NAME
BT_HitBox - ( struct IBox * )
FUNCTION
Get the hitbox bounds of the gadget object. This attribute is normally
only usefull for class writers. Please note that the contents of the
returned IBox structure is only valid _after_ you let this class
render itself. For example suppose the following code is your class
dispatcher:
__saveds __asm ULONG
dispatcher ( __a0 Class *cl, __A2 Object *obj, __A1 Msg msg )
{
struct IBox *domain;
switch ( msg->MethodID ) {
...
case GM_RENDER:
/*
** First let the superclass render.
**/
if ( ! DoSuperMethodA( cl, obj, msg ))
return( 0L );
/*
** Now you can obtain the object
** it's hitbox bounds.
**/
DoSuperMethod( cl, obj, OM_GET,
BT_HitBox, &domain );
...
break;
}
}
Please note that the pointer returned is READ-ONLY. If you need to
adjust it's contents you should make a private copy of the data.
Applicability is (G).
NAME
BT_LabelObject, BT_FrameObject -- ( Object * )
FUNCTION
Set or get the frame/label object to use. Normally only class writers
use these attributes. You can use them to obtain a pointer to the
label/frame object or to erase/change the label/frame object. If, for
example, your class uses it's own custom rendering you can dispose of
the baseclass frame by setting it to NULL like this:
SetAttrs( object, FRM_FrameObject, NULL, TAG_END );
Default is the frame/label build from the attributes passed to the
object at create time. Applicability is (SG).
SEE ALSO
intuition.library/SetAttrs()
NAME
BT_TextAttr -- ( struct TextAttr * )
FUNCTION
Set the font which will be used by the frame and label of the class.
Class writers might want to intercept and copy this data before
passing it onto the superclass.
Default is NULL. Applicability is (S).
NAME
BT_NoRecessed -- ( BOOL )
FUNCTION
To tell the baseclass not to recess the frame when the gadget object
is selected. The checkboxclass uses this attribute.
NAME
BT_LabelClick -- ( BOOL )
FUNCTION
To tell the baseclass to also consider clicking inside the gadget
label as a hit.
Default is FALSE. Applicability is (I).
SEE ALSO
Methods/GM_GADGETHIT
NOTE
All frameclass and labelclass attributes are also valid when creating
a baseclass object.
NAME
BT_HelpText -- ( STRPTR)
FUNCTION
To setup a text which will be displayed if the help-key is pressed
while the mouse pointer is located above the object. This attribute
should be used to attach small on-line help to the object. The text
you specify will be shown in a small BGUI_RequestA() type of requester
so you must make sure that everything fit's nicely on a 600x200
screen.
The specified text may contain any of the infoclass command sequences.
This attribute overides the BT_HelpFile, BT_HelpNode and BT_HelpLine
attributes.
Default is NULL. Applicability (IS).
SEE ALSO
BT_HelpFile, BT_HelpNode, BT_HelpLine, infoclass/INFO_TextFormat,
bgui.library/BGUI_RequestA()